chore(fields): narrow the datetime style cast, and make the #7443 changeset accurate for consumers - #7792

Fixes #7747

Two non-blocking follow-ups recorded from the contract review of #7621. Both are in this one PR because the card carries both; neither ships anything.

Clause-②: no holds and was re-measured, not assumed — see Runtime behaviour is unchanged below.

Item 1 — the #7443 changeset's byte-identity sentence, corrected for consumers

The claim was true measured in this repository (no in-repo datetime field authors a format) but a changeset is a release-note input read by consumers who are not this repository, and #7621 made DateTimeCellRenderer start reading field.format.

What an unrecognised format actually does — MEASURED, not assumed

The card flagged that the value domain is unanswered, so it was measured rather than guessed. A temporary harness rendered DateTimeCellRenderer at one instant (2024-07-04T07:00:00.000Z, en-US) across nine authored values. The harness was deleted after the reading and is not part of this PR.

An unrecognised value is neither rejected nor passed through, and it does NOT fall back to 'compact' — it silently selects the verbose formatDateTime default. formatDateTime branches on options.style === 'compact' and everything else falls to the default face; the cell's || 'compact' only catches the falsy values, which is why '' and null stay compact.

That matters because before #7621 the cell ignored field entirely and always painted the compact face (git show 81a2eb1fb^:packages/fields/src/index.tsx — it destructured value only). So a consumer that authored any non-empty, non-'compact' format on a datetime field sees its cells change. That is the one visible consequence the changeset did not spell out.

The vocabulary gap — and one correction to the card

The card says @objectstack/spec "declares no format on datetime fields". Measured, that is not quite right, and the accurate finding is a stronger version of the same point. The spec's field schema does carry format, on a single flat (non-discriminated) field schema shared by every field type:

format type: optional | desc: "Format string (e.g. email, phone)"
inner type: string | entries: null      (no enum, no per-type domain)

  "compact"          ACCEPTED
  "not-a-real-style" ACCEPTED
  ""                 ACCEPTED
  "short"            ACCEPTED

So format exists but is an unconstrained free-form string whose documented examples are for other field types entirely. There is no declared datetime vocabulary in either @object-ui/types (format?: string) or the spec to check a value against. The corrected sentence names that gap instead of papering over it, as the card asked.

The diff — prose only, name set unchanged

diff --git a/.changeset/7443-datetime-compact-style.md b/.changeset/7443-datetime-compact-style.md
index c7190f6f2..70900b838 100644
--- a/.changeset/7443-datetime-compact-style.md
+++ b/.changeset/7443-datetime-compact-style.md
@@ -13,8 +13,22 @@ The cell now reads `field.format` (it destructured `value` only, so a
 `datetime` field could not reach the style vocabulary a `date` field has) and
 renders through the shared function, and `data-table`'s `formatCellValue`
 calls `formatDateTime` instead of a third, independently authored option bag.
-Every existing cell renders byte-identically; `'compact'` is today's face
-named and rehoused, not a new one.
+Every existing cell without an authored `format`, and every cell authoring
+`'compact'`, renders byte-identically; `'compact'` is today's face named and
+rehoused, not a new one. A `datetime` field that authors any OTHER non-empty
+`format` does change: the cell previously ignored `field` altogether and always
+painted the compact face, and now anything other than `'compact'` selects the
+verbose `formatDateTime` default — measured as `Jul 4, 2024, 07:00 AM` in
+`en-US` for the instant whose compact face is `7/4/2024 7:00 am`. An
+unrecognised value is neither rejected nor passed through; it silently lands on
+that verbose face. No `datetime` field in this repository authors a `format`, so
+no cell here moves — a consumer that authored one is the case this sentence is
+for. Note that `format` has no declared value vocabulary to check a value
+against: `@object-ui/types` types it `format?: string`, and `@objectstack/spec`
+carries one free-form `format?: string` on its shared field schema, described
+"Format string (e.g. email, phone)" and accepting any string. `'compact'` is
+therefore the only value with a defined `datetime` meaning, and every other
+value means "the verbose face" by fallthrough rather than by design.
 
 Additive, no signature change: `formatDateTime(value, options?)` is unchanged
 and `formatDateTime(v, { locale })` keeps meaning what it meant.

The gate that governs this file prints the checkability itself. node scripts/check-changeset-overwrite.mjs, exit 0:

Compared the working tree with 6771c805a (merge-base with origin/main): 1 changeset(s) added, 1 modified, 0 deleted.

      M  .changeset/7443-datetime-compact-style.md
             declared at base: @object-ui/core: minor, @object-ui/fields: minor, @object-ui/components: patch
             declares now:     @object-ui/core: minor, @object-ui/fields: minor, @object-ui/components: patch

declared at base and declares now are identical: all three package names kept, all three bump levels kept, frontmatter byte-for-byte unchanged. Mechanically:

$ diff  (frontmatter at origin/main, sorted)  (frontmatter now, sorted)
IDENTICAL: frontmatter byte-for-byte unchanged, no package name added or dropped

This is the "factual correction to prose" case the gate's own history measurement counts among its 19-for-19 legitimate modifications, and it keeps the 18-for-19 name-preservation shape.

Item 2 — (field as any)?.format narrowed to the subtype that declares it

diff --git a/packages/fields/src/index.tsx b/packages/fields/src/index.tsx
index bb0974998..c16ba226e 100644
--- a/packages/fields/src/index.tsx
+++ b/packages/fields/src/index.tsx
@@ -7,7 +7,7 @@
  */
 
 import React from 'react';
-import type { FieldMetadata, SelectOptionMetadata } from '@object-ui/types';
+import type { DateTimeFieldMetadata, FieldMetadata, SelectOptionMetadata } from '@object-ui/types';
 import { ComponentRegistry, percentDisplayValue, getRecordDisplayName, humanizeLabel, isMissingForRequired, formatDate, formatDateTime, formatDateTimeCompactParts, formatRelativeDate, type ComponentMeta, type DateDisplayOptions } from '@object-ui/core';
 // The platform's own value-shape contract, asked rather than restated
 // (objectui#6744). See `locationStoredValueSchemaFor` below for why this is a
@@ -882,7 +882,11 @@ export function DateTimeCellRenderer({ value, field }: CellRendererProps): React
   // (objectui#7443). `||`, not `??`, matches the `date` cell and keeps an
   // authored empty string on the compact face rather than dropping it into
   // the verbose default.
-  const style = (field as any)?.format || 'compact';
+  // `FieldMetadata` is a 37-member union and `BaseFieldMetadata` carries no
+  // `format`, so the bare property read is `TS2339` — SOME cast is load-bearing.
+  // `DateTimeFieldMetadata` is the narrowest one that carries it (objectui#7747);
+  // `as any` would also silence a typo in the property name, this does not.
+  const style = (field as DateTimeFieldMetadata | undefined)?.format || 'compact';
 
   // The compact face is painted in two halves — the time is muted and offset
   // — so this branch asks the shared module for the halves rather than the

Some cast is load-bearing: FieldMetadata is a 37-member union, BaseFieldMetadata carries no format, so a bare field.format is TS2339. But as any was wider than the job — DateTimeFieldMetadata is exported from @object-ui/types (packages/types/src/index.ts:465, format?: string at field-types.ts:301) and this file already imports types from there, so the narrow cast cost one word in an existing import.

no-explicit-any is warn-level here, so Lint is green either way; the count still moves and is checkable:

BEFORE  no-explicit-any warnings in packages/fields/src/index.tsx: 46   (one of them line 885)
AFTER   no-explicit-any warnings in packages/fields/src/index.tsx: 45   (none on lines 880-895)

Exactly one warning removed, and it is the line changed here. No other any in the file was touched and the rule was not raised to error — both are other cards.

The narrowing is load-bearing — lit control, not an assertion

as any could never have gone red, so it measures nothing as a control. Instead the cast was temporarily swapped to BooleanFieldMetadata — exported from the same barrel, extends BaseFieldMetadata, and adds only type, so it genuinely does not carry format. The import was swapped with it, otherwise tsc would have answered TS2304 (unknown name) and the reading would have measured the import rather than the property check.

HEAD_BLOB      = c16ba226ee14a60e1cefcc37e8a0ba4e90cc91a7
PRE_MUTATION   = c16ba226ee14a60e1cefcc37e8a0ba4e90cc91a7
MUTATION: injected-text count=1  original-text count=0        ** mutation proven on disk
POST_MUTATION  = a437836f3b699c2e5c57ed13af6a7834be07f461
mutated line   : 889:  const style = (field as BooleanFieldMetadata | undefined)?.format || 'compact';

=== TSC_EXIT=2 ===
src/index.tsx(889,62): error TS2339: Property 'format' does not exist on type 'BooleanFieldMetadata'.

RED, and it names the exact line and column of the cast. That is the property as any was suppressing: tsc really does check .format against the cast type now.

Restoration, proven rather than claimed (restore leg is git checkout HEAD -- ABSOLUTE_PATH, never the bare form, which restores from the index and would hand the mutation back; the script carries trap restore EXIT INT TERM for the crash path, but the proof below is the hash, not the trap firing):

POST_RESTORE   = c16ba226ee14a60e1cefcc37e8a0ba4e90cc91a7
HEAD_BLOB      = c16ba226ee14a60e1cefcc37e8a0ba4e90cc91a7
HASH: EQUAL — byte-identical to the HEAD blob
git diff HEAD: EMPTY (clean tree)
restored text  : 1 occurrence(s) of the real cast

Runtime behaviour is unchanged (the Clause-② void condition, checked)

The cast is erased at emit; the expression (field)?.format || 'compact' is byte-for-byte the same JavaScript. The measured table in item 1 was produced after the narrowing and reproduces the pre-existing behaviour on every row, 'compact', empty, null and unrecognised alike. Nothing in this PR makes DateTimeCellRenderer read a different value at runtime, so the declared Clause-②: no stands.

Changeset

.changeset/7747-datetime-format-cast-narrowing.md is a new file with empty frontmatter — item 2 touches a released package's src/, so AGENTS.md:161 requires a declaration, and a type-level-only change releases nothing. The item 1 correction is a different file and does not satisfy that requirement.

$ node scripts/check-changeset-presence.mjs     # exit 0
1 source file(s) of 1 released package(s) changed, and this change declares 1 changeset(s):
.changeset/7747-datetime-format-cast-narrowing.md.
Every one of them has an EMPTY frontmatter — declared as releasing nothing, which
is the explicit exemption and a complete answer to this gate.

Verification

All readings below were taken at the final commit a2ee8a2, on a clean tree (git status --porcelain empty). Heavy runs went through the container's shared verify lock; wall-clock figures are shared-box seconds, so only the pass/fail counts are quoted.

Every gate exit code above was captured with the command redirected to a file before the status was read, never after a pipe.

One out-of-scope finding, filed not fixed

Filed as #7791. pnpm --filter @object-ui/fields test reports 2 failures in CapabilityMultiSelectField.specParity-6285.test.tsx on this tree — that test sets VOCABULARY_ROOT = '.' (the process cwd), and the package-level script leaves cwd at packages/fields while --root only moves vitest's root. From the repo root the same file is 7 passed (7). It is unrelated to this diff, which touches neither that test nor its subject: the isolated control (cd packages/fields plus the package script's own vitest form, same tree) reproduces it with cwd as the only variable, and the same file from the repo root is green. A pristine origin/main checkout was not run — the causal argument here is the cwd control, not a baseline comparison. Out of scope for this card, so it was filed rather than fixed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KbJQ1y1J12nZxYzFWhP8Q3

Generated by Claude Code